<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

<HTML>
  <HEAD>
  <TITLE>Using ARP Without Jena</TITLE>

 <LINK REL ="stylesheet" TYPE="text/css" 
	HREF="../javadoc/stylesheet.css" TITLE="Style">
 <link rel="stylesheet" type="text/css" href="../styles/doc.css" />
<style>
td { text-align:left; } 
  </style>
  </HEAD>
  <BODY>
  <h1>Using ARP Without Jena</h1>
<p>
ARP can be used both as a Jena subsystem, or
as a standalone RDF/XML parser.
This document gives a quick guide to using ARP standalone.
</p>
<h2>Contents</h2>

<ul>
 <li><a href="#overview">1. Overview</a></li>
 <li><a href="#sample">2. Sample Code</a></li>
 <li><a href="#handlers">3. ARP Event Handling</a></li>
 <li><a href="#config">4. Configuring ARP</a></li>
 <li><a href="#interrupt">5. Interrupting ARP</a></li>
 <li><a href="#sax2rdf">6. Using Other SAX Sources</a></li>
 <li><a href="#memory">7. Memory usage</a></li>
 </ul>


<h2><a name="overview">1. Overview</a></h2>
<p>
To load an RDF file:
</p>
<ol>
<li>Create an 
<A HREF="../javadoc/com/hp/hpl/jena/rdf/arp/ARP.html#ARP()">
ARP</a> instance.</li>
<li>Set parse options, particularly error detection control,
using 
<A HREF="../javadoc/com/hp/hpl/jena/rdf/arp/ARPConfig.html#getOptions()">
getOptions</A> or 
<A HREF="../javadoc/com/hp/hpl/jena/rdf/arp/ARPConfig.html#setOptionsWith(com.hp.hpl.jena.rdf.arp.ARPOptions)">
setOptionsWith</A>.</li>
<li>Set its handlers, by calling the

<A HREF="../javadoc/com/hp/hpl/jena/rdf/arp/ARPConfig.html#getHandlers()">
getHandlers</A> or 
<A HREF="../javadoc/com/hp/hpl/jena/rdf/arp/ARPConfig.html#setHandlersWith(com.hp.hpl.jena.rdf.arp.ARPHandlers)">
setHandlersWith<A>
methods, and then.<ul>
<li>Setting the 
<A HREF="../javadoc/com/hp/hpl/jena/rdf/arp/ARPHandlers.html#setStatementHandler(com.hp.hpl.jena.rdf.arp.StatementHandler)">
statement handler</A>.</li>
<li>Optionally setting the other handlers.</li>
</ul>
</li>
<li>Call a 
<A HREF="../javadoc/com/hp/hpl/jena/rdf/arp/ARP.html#load(java.io.InputStream, java.lang.String)">load</A> method</li>
</ol>
<p>
Xerces is used for parsing the XML.
The SAXEvents generated by Xerces are then
analysed as RDF by ARP. It is possible to
use a different source of SAX events.
</p>
<p>
Errors may occur
in either the XML or the RDF part.</p>

<h2><a name="sample">2. Sample Code</a></h2>
<pre>
    ARP arp = new ARP();
        
 // initialisation - uses ARPConfig interface only.
 
    arp.getOptions().setLaxErrorMode();
        
    arp.getHandlers().setErrorHandler(new ErrorHandler(){
    	public void fatalError(SAXParseException e){
               // TODO code
    	}
		public void error(SAXParseException e){
				// TODO code
		}
		public void warning(SAXParseException e){
				// TODO code
		}
    });
    arp.getHandlers().setStatementHandler(new StatementHandler(){
    public void statement(AResource a, AResource b, ALiteral l){
        	// TODO code
    }
	public void statement(AResource a, AResource b, AResource l){
	        // TODO code
    }
    });
 
 // parsing.
 
    try {
    // Loading fixed input ...
        arp.load(new StringReader(
        "&lt;rdf:RDF  xmlns:rdf='http://www.w3.org/1999/02/22-rdf-syntax-ns#'>\n"
        +"&lt;rdf:Description>&lt;rdf:value rdf:parseType='Literal'>"
        +"&lt;b>hello&lt;/b>&lt;/rdf:value>\n"
        +"&lt;/rdf:Description>&lt;/rdf:RDF>"
        ));
        
    }
    catch (IOException ioe){
           // something unexpected went wrong	
    }
    catch (SAXParseException s){
        	// This error will have been reported
    }
    catch (SAXException ss) {
            // This error will not have been reported.
    }
</pre>        


<h2><a name="handlers">3. ARP Event Handling</a></h2>

<p>
ARP reports events concerning:
</p>
<ul>
<li>Triples found in the input.</li>
<li>Errors in the input.</li>
<li>Namespace declarations.</li>
<li>Scope of blank nodes.</li>
</ul>
<p>
User code is needed to respond to any of these events
of interest. This is written by implementing any of the
relevant interfaces:

<A HREF="../javadoc/com/hp/hpl/jena/rdf/arp/StatementHandler.html">
StatementHandler</A>,
org.xml.sax.ErrorHandler,
<A HREF="../javadoc/com/hp/hpl/jena/rdf/arp/NamespaceHandler.html">
NamespaceHandler</A>,
and
<A HREF="../javadoc/com/hp/hpl/jena/rdf/arp/ExtendedHandler.html">
ExtendedHandler</A>.
</p>
<p>
An individual handler is set by calling the
<A HREF="../javadoc/com/hp/hpl/jena/rdf/arp/ARPConfig.html#getHandlers()">
getHandlers</A>
 method on the ARP instance. This returns an encapsulation
of all the handlers being used. A specific handler 
is set by
calling the appropriate set...Handler method on that object,
e.g. 
<A HREF="../javadoc/com/hp/hpl/jena/rdf/arp/ARPHandlers.html#setStatementHandler(com.hp.hpl.jena.rdf.arp.StatementHandler)">
setStatementHandler</A>.
</p>
<p>
All the handlers can be copied from one ARP instance to another
by using the 
<A HREF="../javadoc/com/hp/hpl/jena/rdf/arp/ARPConfig.html#setHandlersWith(com.hp.hpl.jena.rdf.arp.ARPHandlers)">
setHandlersWith</A>
 method:
</p>
<pre>
   ARP from, to;
   // initialize from and to
   // ...
   
   to.setHandlersWith(from.getHandlers());
</pre>
<p>
The error handler reports both XML and RDF errors, the former detected
by Xerces.
See 
<A HREF="../javadoc/com/hp/hpl/jena/rdf/arp/ARPHandlers.html#setErrorHandler(org.xml.sax.ErrorHandler)">
ARPHandlers.setErrorHandler</A> for details
of how to distinguish between them.</p>

<h2><a name="config">4. Configuring ARP</a></h2>

<p>
ARP can be configured to treat most error conditions as warnings
or to be ignored, and to treat some non-error conditions as
warnings or errors.
</p>
<p>
In addition, the behaviour in response to input that does not have an
<code>&lt;rdf:RDF&gt;</code> root element is configurable: either to
treat the whole file as RDF anyway, or to scan the file looking
for embedded  <code>&lt;rdf:RDF&gt;</code> elements.
</p>
<p>
As with the handlers, there is an options object that encapsulates
these settings. It can be accessed using 
<A HREF="../javadoc/com/hp/hpl/jena/rdf/arp/ARPConfig.html#getOptions()">
getOptions</A>, 
and then individual settings can be made using the methods in
<A HREF="../javadoc/com/hp/hpl/jena/rdf/arp/ARPOptions.html">
ARPOptions</A>.
</p>
<p>
It is also possible to copy all the option settings
from one ARP instance to another:
</p>
<pre>
   ARP from, to;
   // initialize from and to
   // ...
   
   to.setOptionsWith(from.getOptions());
</pre>
<p>
The 
<a href="../IO/iohowto.html#arp-properties">I/O how-to</a> gives some more detail about the options
settings, although it assumes the use of the Jena RDFReader interface.
</p>


<h2><a name="interrupt">5. Interrupting ARP</a></h2>
<p>
It is possible to interrupt an ARP thread.
See the <a href="../IO/iohowto.html#arp-interrupt">I/O how-to</a> for details.
</p> 

<h2><a name="sax2rdf">6. Using Other SAX Sources</a></h2>

<p>
It is possible to use ARP with other SAX input sources,
e.g. from a non-Xerces parser, or from an in-memory XML
source, such as a DOM tree.
</p>
<p>
Instead of an ARP instance, you create an instance
of
<A HREF="../javadoc/com/hp/hpl/jena/rdf/arp/SAX2RDF.html">
SAX2RDF</A> using the<A HREF="../javadoc/com/hp/hpl/jena/rdf/arp/SAX2RDF.html#newInstance(java.lang.String)">
newInstance</A> method. This can be configured just like an ARP instance,
following the initialization section of the 
<a href="#sample">sample code</a>.
</p>
<p>
This is used like a SAX2Model instance as 
<a href="sax.html">described elsewhere</a>.
<h2><a name="memory">7. Memory usage</a></h2>
<p>
For very large files, ARP does not use any additional
memory except when either the 
<A HREF="../javadoc/com/hp/hpl/jena/rdf/arp/ExtendedHandler.html#discardNodesWithNodeID()">
ExtendedHandler.discardNodesWithNodeID</A>
returns false or when the 

<A HREF="../javadoc/com/hp/hpl/jena/rdf/arp/AResource.html#setUserData(java.lang.Object)">
AResource.setUserData</A> 
method has been
used. 
In these cases ARP needs to remember the <code>rdf:nodeID</code>
usage through the file life time. </p>

 </BODY>
</HTML>